AI 功能
这篇帮你做什么：接入自己的模型服务，为聊天、图片文字提取、图片内容理解、语音转文字和群消息总结配置模型。入口是 AI 管理，包含服务设置、提示词设置、消息总结、运行与用量四页。
开始前确认
- 应用不保证自带可用模型、密钥或免费额度。先向所选服务商获取账号、模型名称、接口地址和 API Key（调用服务的密钥），了解收费及余额限制。
- 连接测试和实际任务都可能消耗额度。 应用中的每日 Token 限额是调用量限制，不是服务商的金额账单；Token 是模型计量输入、输出长度的单位。
- 群消息、图片或语音可能发送到你选择的模型服务。启用前确认测试群授权、服务商隐私政策和所需数据范围，不发送不应外传的内容。
- 控制台没有应用层登录保护，应只在可信网络访问。不要把密钥写进提示词、群消息、截图或普通备注；备份文件也需要妥善保管。
- 模型能聊天，不代表它也支持图片或音频。页面勾选能力只是声明，不能替服务商增加能力。
四类对象的关系与选择
AI 管理里的配置分成四层，上层就绪不等于下层就绪，一个任务可用需要四层全部到位：
| 对象 | 是什么 | 在哪配 | 就绪条件 |
|---|---|---|---|
| 模型 | 到某个服务商的一条连接：地址、密钥、能力声明 | 服务设置 → 添加模型 | 已保存、启用、凭据有效 |
| 任务 | 应用内的能力槽位（聊天、图片 OCR、图片理解、语音转文字、群消息总结） | 服务设置 → 任务分配 | 已分配模型并打开"使用此任务" |
| 提示词 | 按任务和版本管理的配置；正文是否发送取决于任务 | 提示词设置 | 已选定生效版本并"启用此任务" |
| 场景 | 任务在哪个功能里实际被触发 | 消息总结页 / 群聊监控 / 群基本设置 | 满足该场景的开关、输入和触发条件 |
选择建议：想让机器人回应群里的提问，用任务"聊天"，在群基本设置打开 AI Chat 群级开关，由成员 @机器人 触发；它不是指令目录里的聊天指令。想让机器人看懂图片或语音，用对应媒体任务并在群聊监控开群级识别；想给群消息生成一份回顾，用"群消息总结"并保持"投递到群"关闭，先在控制台看结果。只想回复固定答案、不需要模型时，用问答更省额度。
群开关与模型、任务开关是独立配置：打开模型不会自动打开任何群。AI Chat 和媒体识别的群开关默认关闭；群总结则在每次创建时选择群和范围，没有一个需要常开的群总结开关。
额度与数据外传
- 全局额度约束所有任务向服务商发起的新请求。
- 群级额度在 群设置 → 基本设置 的 AI 用量卡片，只额外约束 聊天和群消息总结；未配置时按每日 409600 Token。图片文字提取、图片理解和语音转写只扣全局额度。因此某群额度设为 0 不能停止该群的媒体识别。
- 外传内容由任务决定：群总结发送所选范围内的消息时间、显示名和纯文本；没有显示名时会回退到用户 ID，当前不发送 OCR/语音转写的派生文本。聊天发送对话文本及相应提示词；图片、语音任务会发送所需媒体或内容。总结范围要在创建时核对；其他场景还要核对群开关。
- 费用只在服务商侧发生：应用只记录调用次数与 Token 估算，"费用未知（不计为 0）"就是字面意思——账单金额到服务商处查询。运行台账中的模型、提示词版本、用量等记录不能当成外发正文的完整副本。
通用配置（服务设置页顶部）
- 全局每日 Token 限额：所有任务共用的每日调用量上限。填 0 会冻结需要访问模型服务商的新请求，不取消已经发出的请求。图片/语音的已缓存结果、相同群与消息快照及范围模式的历史成功总结仍可能被直接复用，不调用模型、不再次扣额度；因此它是外部调用止损手段，不是停止所有结果输出的总开关。
- 提示词历史版本保留天数：1–90 天，默认 30 天。超过保留天数的旧提示词版本会被定期清理，正在使用的版本不会被删除。
第一步：添加模型连接
打开 AI 管理 → 服务设置，在模型区域点 添加模型。
如有合适的服务商预设，可用它预填地址和接口类型；仍须与服务商当前说明核对。
填好这几项：
字段 怎么填 显示名称 自己容易辨认的名字，用于控制台展示 服务商模型名称 服务商提供的准确模型标识，不是自取名称 API 地址 完整接口地址，包含所选接口要求的路径；不要只填网站首页 API Key 服务商签发的密钥，填到专用密码输入框 接口类型 与服务商实际支持的接口对应 支持的内容类型、适合处理的任务 只声明服务商确实支持的能力 核对启用此模型，点 保存设置。输入长度、回复长度等限制应依据模型规格设置，不确定时不要随意抬高。
重新打开模型确认配置已保存。密钥之后只显示已配置或脱敏值，不能通过回读得到原文；编辑时留空保留现有密钥，换密钥则输入新值。
准备好费用与数据授权后，可以执行连接测试并查看连接测试记录。测试通过也不等于所有任务和群设置都已准备好。
API 地址和接口类型填错时，即使密钥正确也可能失败。不要反复换密钥来掩盖地址问题。
第二步：给任务分配模型
在服务设置的任务分配中选要启用的任务。
配置首选模型；确有需要时添加备用模型。备用模型也必须支持同一任务，并有自己的可用凭据。
核对任务路由参数：
参数 取值 说明 超时 1–600 秒 等待服务商响应的时长；超时不自动重试 单次最大回复长度 1–32000 Token 限制模型单次输出的长度 温度 0–2（步进 0.1） 越高输出越发散；追求稳定回复用低值 打开 使用此任务并保存。
一个模型可以供多个任务使用，但任务不会因为添加了模型就自动完成所有配置。首选模型不可用时可能尝试备用模型；不要把"停用首选模型"当成停止整个任务的办法。
第三步：选定并启用提示词
提示词是告诉模型"要做什么、按什么方式回答"的说明，与普通群提示或指令回复模板不同。
- 打开 AI 管理 → 提示词设置，选择与任务分配相同的任务。
- 查看当前模板；需要修改时保存为提示词版本。首次先保留系统预填内容，避免同时改模型和模板导致难以排查。
- 在生效设置选定要使用的版本，打开 启用此任务并保存。
- 核对页面就绪提示：模型分配与提示词都启用，才具备发起该任务的前提。
只保存新提示词版本，不代表它已成为正在使用的版本。旧版本会按"通用配置"里的保留天数清理；想回退到某个版本时，先确认它仍在版本列表中。不要把普通模板变量直接粘到 AI 提示词里；以该任务允许的变量和界面说明为准。
不同任务实际使用的正文不同：聊天使用系统提示词和用户消息模板；群总结只用系统提示词，用户内容由系统按消息生成。图片 OCR、图片理解和语音转写当前仍要求存在并启用提示词版本，但不会把自定义提示词正文发送给模型，语音的“转写提示”也不进入转写请求。不要靠修改这些正文来约束媒体识别行为。
第四步：配置实际使用场景
- 群消息总结：打开 AI 管理 → 消息总结，点 创建总结，选择群、范围模式和 投递到群 开关。范围模式二选一：最近 N 条（1–1000，默认 100）或 时间段。"投递到群"默认关闭，此时只在控制台查看，不会发进群。列表可按状态、触发来源、范围筛选；详情显示实际消息数、缺失情况和错误原因。还需要可读取的消息，不能凭空总结。当前媒体派生文本不进入总结；详情“缺失媒体”为 0 也不能证明图片和语音都已被理解。具体外传内容按上文核对，不要仅凭页面提示推断。
- 图片或语音监控：按群聊监控检查对应群开关。任务就绪不等于所有群都已开启媒体识别。
- 群内 AI Chat：在群基本设置打开 AI Chat 群级开关，核对聊天任务就绪，由成员 @机器人 触发。无需在指令目录配置聊天关键词；前序指令或监控已受理消息等情况仍会影响实际触发。
先在可控测试群启用一个场景，确认实际输出后再扩大范围。
怎样判断成功或失败
依次区分：配置保存、任务就绪、请求完成、消息实际送达。模型生成了内容，不代表机器人已经把它发进群。"已受理不是平台成功、结果未知不重发"的通用判读方法见结果判断与排障。
在 AI 管理 → 运行与用量 分三处核对：
- 执行准备：显示"可执行 / 配置不完整 / 尚未配置模型"、可执行模型数和已覆盖任务类型。不是"可执行"时按页面给出的原因处理（模型未启用、密钥未配置、任务未分配或未启用等），页面通常会给出下一步入口。
- 全局 Token 预算：显示上限、已用、剩余和预算状态；预算"不可用"或被冻结时，需要访问服务商的新请求会被拒绝，已有结果复用见上文。若页面提示"预算使用记录恢复未完成"，为避免放宽额度，请求同样会被拒绝，系统会继续尝试恢复预算记录，不是自动重发业务请求。
- 运行状态与调用诊断：按模型列出启用、密钥、任务分配情况，以及最近业务调用和向服务商发请求的记录，用于区分"没发起调用""调用失败""调用成功但没发进群"。
页面上的"费用未知（不计为 0）""结果未证实"表示应用只知道发出过请求、不知道服务商实际扣费或最终结果，不要把它们当成零成本或成功；账单金额仍需到服务商处查询。遇到未配置、任务停用、密钥缺失、能力不支持、超时或额度限制时，按具体原因处理，不笼统归为"AI 没反应"。
- 没有可选模型：检查模型是否已保存、启用并声明所需能力。
- 服务商拒绝：核对完整地址、接口类型、密钥权限、模型名称和余额。
- 页面已就绪但群里无输出：检查实际触发入口、群开关、可用消息和平台发送结果。
- 提示预算或计量异常：先停用受影响任务，再检查运行与用量中的原因；不要未经确认就提高额度或反复重试。
配置迁移
服务设置提供 导出脱敏配置和导入配置。导出文件不含 API Key 或敏感请求头明文，迁移后仍需重新配置凭据。导入会在现有配置上追加模型记录，不覆盖同名模型；文件会先做格式检查，原配置中使用过密钥的模型和敏感 Header 需要逐项补录凭据后才允许确认导入。它不是完整的数据备份，也不是数据恢复方法。
关闭或改回：按想停的范围选手段
停用某个模型不是停止整个 AI：停掉的模型退出候选后，配置了备用模型的任务可能继续由备用模型执行；即使没有备用模型，也只是这一个模型不可用。按下表选择正确的停止层级：
| 你想停的是什么 | 做法 | 不会停止什么 |
|---|---|---|
| 某一个任务（如群消息总结） | 任务分配中关闭 使用此任务并保存；也可停用该任务提示词 | 其他任务仍正常运行 |
| 某个模型参与执行 | 模型卡片选 停用模型，任务分配保持不变；恢复时重新启用 | 有备用模型的任务会改用备用模型继续 |
| 全部向模型服务商发起的新请求 | 服务设置顶部 全局每日 Token 限额 改为 0，保存 | 已发请求不取消；缓存/历史结果仍可能复用 |
| 某个群的媒体识别 | 关闭该群在群聊监控的对应开关并保存 | 模型与其他群不受影响 |
| 某个群的自动 AI Chat | 关闭该群基本设置的 AI Chat 群级开关并保存 | 群总结、媒体识别与其他群不受影响 |
| 某个群聊天/总结的新外部调用 | 群级每日 Token 额度设为 0 并保存 | 不停止媒体识别，不阻止历史总结复用，其他群不受影响 |
不可逆与副作用：
- 删除模型会连带清理它的任务分配、请求 Header 和密钥，不可恢复——只想暂停时不要删除。
- 清除密钥会物理删除凭据记录，绑定该模型的任务会报"凭据未配置"直到重新配置；它不撤销已发送的数据，也不会退款。
- 改回提示词：在生效设置重新选择原版本（确认它仍在保留期内）。
- 停止配置不能撤回服务商已经收到的请求或群里已经发送的回复。费用、历史消息和密钥管理应分别处理。